New Star Software Collection

home *** CD-ROM | disk | FTP | other *** search

/ New Star Software Collection / NSS_Collection.iso / 3-170 dbase 10 for windows / 1.ima / DOC.PAK / UI_EXTEN.TXT < prev next >

Wrap

Text File | 1993-07-26 | 21.0 KB | 550 lines

Copyright (c) 1991-1993 Borland International, Inc. All Rights Reserved. THE BLADERUNNER UI LANGUAGE EXTENSIONS -------------------------------------- Bladerunner extends the dBASE language with new commands and functions for creating graphical, event-driven user interfaces. For compatibility with DOS applications, Bladerunner still supports the dBASE IV windowing and menu mechanisms. However, to take full advantage of the Windows environment, you need to understand and use the new extensions. This document introduces the new UI extensions and describes the steps for creating and using windows. Contents -------- I. Overview II. Summary of Steps III. Step 1 - Define the window IV. Step 2 - Define controls V. Step 3 - Assign actions VI. Step 4 - Read the window VII. Upgrading dBASE DOS screen forms Overview -------- In a Bladerunner application, the window is the primary user interface container. Windows can contain controls, such as entry fields and list boxes, for interacting with the user and can also contain other windows. When you design the user interface for your application, you are essentially designing its windows. The Bladerunner mechanism for working with windows is familiar to dBASE IV programmers, with these important differences: - In dBASE IV, there is an active state for GETs (READ) and an active state for menus (ACTIVATE MENU/POPUP); both can be visible, but only one at a time is active. In Bladerunner, there is a single active state for a window. Use READMODAL() or OPEN WINDOW to activate GETs (called entry fields), menus, and any other controls in the window. - In dBASE IV, only one window at a time can be active. In Bladerunner, several windows can be active at once. A new command, OPEN WINDOW, displays a window and continues program execution, letting you display more windows, or execute other code, without stopping execution to get user responses. - In dBASE IV, you DEFINE a window, ACTIVATE it, display your SAYs and GETs, then READ. In Bladerunner, you don't ACTIVATE windows; instead, you DEFINE the window, DEFINE controls OF the window, then READMODAL() or OPEN WINDOW. The next section describes these steps in more detail. Summary of Steps ---------------- Below is a summary of the steps for creating and reading a Bladerunner window. A detailed explanation of each step follows the summary. 1. Define the window with DEFINE WINDOW 2. Define controls for the window with DEFINE <control name> OF <window name> 3. Assign actions with ON SELECTION WINDOW ON SELECTION PULLDOWN 4. Read the window with READMODAL() or OPEN WINDOW Step 1 - Define the Window -------------------------- DEFINE WINDOW has several options for specifying the look and behavior of the window. Using these options in different combinations, you can define input windows, dialog boxes or any other kind of window. Type HELP DEFINE WINDOW from the Command Window for a list of options. The Default Font and the Coordinate Plane Each window has a default font which Bladerunner uses to display any controls or output that don't specify a font. Use the FONT option of DEFINE WINDOW to set the window's default font. If you don't use the FONT option, the default font is the Windows system font. A window's default font is especially important because it defines the size of the coordinate plane for placing controls in the window. That is, the row height is determined by the line height of the default font, and the column width is determined by the character width of the default font. So, when you issue this command: DEFINE TEXT FNHeading OF MyWindow AT 6,16 PROMPT "First Name" Bladerunner displays "First Name" at row 6 (six lines down in the default font), column 16 (sixteen characters across in the default font). Proportional fonts, such as Helvetica or Times, have varied widths for each character: an "i" takes up less space than a "w." If you specify a proportional font as the default font, Bladerunner uses the average character width as the column width. For this reason, using a non-proportional font as the default window font makes working with window coordinates a little easier. With a non-proportional default font, you can still specify proportional fonts for the controls that contain text. "Specifying Coordinates" in Step 2 describes two new functions, NEXTROW() and NEXTCOL(), for displaying controls with varied fonts. Dialog Boxes A dialog box is a window you create for getting information from the user. The DLGFRAME option of DEFINE WINDOW makes the window's border look like a standard Windows dialog box, and makes the window non-sizeable. These other options of DEFINE WINDOW are useful for creating dialog boxes: NOMAXIMIZE Displays the window without a Maximize button. NOMINIMIZE Displays the window without a Minimize button. AUTOSIZE Automatically sets the lower right coordinate of the window to contain the lowest and rightmost control in the window. This example defines a dialog box for prompting the user to enter a customer name: DEFINE WINDOW MyDialog AT 10,10 OF DESKTOP DLGFRAME NOMAXIMIZE; NOMINIMIZE AUTOSIZE MESSAGE "Enter a customer name" cName = SPACE(30) DEFINE TEXT Head1 AT 2,2 OF MyDialog PROMPT "Customer name:" DEFINE ENTRYFIELD GetName WITH cName at 2,NEXTCOL() OF MyDialog DEFINE PUSHBUTTON Ok AT 4,5 OF MyDialog PROMPT "OK" DEFINE PUSHBUTTON Cancel AT 4,NEXTCOL() OF MyDialog ; PROMPT "Cancel" Step 2 - Define controls ------------------------ A control is an object you place in a window for interacting with the user. Bladerunner provides several controls for displaying and editing data, such as list boxes and radio buttons, and controls for getting user responses, such as pull-down menus and pushbuttons. You place a control in a window by defining the control. Here is the basic syntax: DEFINE <control name> OF <window name> AT <coordinates> The following examples define controls for MyWindow: DEFINE TEXT Get1Title OF MyWindow AT 1,5 PROMPT "Enter a name" DEFINE ENTRYFIELD Get1 WITH mName OF MyWindow AT 1,20 DEFINE PUSHBUTTON Push1 OF MyWindow AT 3,2 PROMPT "OK" DEFINE LISTBOX List1 OF MyWindow FROM 3,10 TO 9,25 PROMPT FILES Specifying coordinates For precise placement of controls, you can specify coordinates with decimal values. For example: DEFINE PUSHBUTTON OK AT 3.5, 1.5 OF MyWindow PROMPT "OK" Controls that contain text, such as entry fields and radiobuttons, have a FONT option. Even though each control you place may specify a different font, the coordinates for placing controls are always based on the window's default font. When positioning controls with different fonts, the relative addressing technique commonly used in dBASE DOS, using ROW() and COL(), can misalign controls. For instance: @ 1,2 SAY "First line" @ ROW()+1,2 SAY "Second line" @ ROW()+1,2 SAY "Third line" will display correctly aligned only if all three objects and the window in which they are displayed use the same font. To accomodate relative addressing with varied fonts, Bladerunner provides NEXTROW() and NEXTCOL(). NEXTROW() returns the next available row on the coordinate plane given the last control drawn; NEXTCOL() returns the next available column. For instance DEFINE FONT Times10 ........ @ 2,2 SAY "First line" FONT Times10 @ NEXTROW(),2 SAY "Second line" FONT Arial24 @ NEXTROW(),2 SAY "Third line" FONT Script48 @ ROW(),NEXTCOL() SAY "Second SAY on Third line" FONT Times10 will display correctly aligned regardless of the fonts you specify. Data Controls These controls display and edit data. ENTRYFIELDs correspond to GETs, and TEXT controls correspond to SAYs. DEFINE... So a user can --------- ------------- ENTRYFIELD Enter a single value COMBOBOX Enter or select one of any number of values SPINBOX Enter or select one in an ordered set of values SCROLLBAR Select one in an ordered set of values CHECKBOX Select one of two logical values RADIOBUTTONS Select one of a few values LISTBOX Select one or more of any number of values BROWSE View or edit fields in a table - tabular view EDIT View or edit fields in a table - record view EDITOR View or edit text BOX See a box TEXT See text as a heading, desc., or instruction. GRAPH See and interact with a graph of table data IMAGE See a bitmapped image Action controls These controls, menus, speedbars, and pushbuttons, cause actions to occur. Bladerunner supports dBASE IV's horizontal bar menus (created with DEFINE MENU and DEFINE PAD) and popup menus (created with DEFINE POPUP and DEFINE BAR) only for dBASE IV compatibility. To create menus in Bladerunner, use these new commands: DEFINE MENU CHOICE Defines an item on the menu bar DEFINE PULLDOWN Defines a pulldown menu DEFINE PULLDOWN CHOICE Defines an item on a pulldown menu ON MENU CHOICE Assigns a pulldown menu to a menu bar item A Bladerunner window can have just one menu bar. Consequently, you don't explicitly define menu bars; you just define each menu item OF the window with DEFINE MENU CHOICE. The menu items display in the order you define them on a bar attached to the top border. Use DEFINE PULLDOWN to define a pull-down menu and DEFINE PULLDOWN CHOICE to define each item on the pull-down menu. Use ON MENU CHOICE to attach a pulldown menu to a menu bar item. Menu bars and pulldown menus become active, along with any other controls in the window, when you read the window. DEFINE MENU CHOICE mFile OF MyWin PROMPT "File" DEFINE MENU CHOICE mEdit OF MyWin PROMPT "Edit" .... DEFINE PULLDOWN pFile DEFINE PULLDOWN CHOICE pFile1 OF pFile PROMPT "Delete" DEFINE PULLDOWN CHOICE pFile2 OF pFile PROMPT "Recall" .... ON MENU CHOICE mFile OF MyWin ACTIVATE PULLDOWN pFile .... A speedbar is a row or column of related buttons that cause an action when pressed. In Windows applications, speedbars typically duplicate menu items, offering a quick way to cause an action without having to find it on a menu. For instance, Print can be an item on the File menu and also a button on the speedbar. Use DEFINE SPEEDBAR to create a speedbar definition and DEFINE SPEEDBUTTON to define each button on the speedbar. DEFINE SPEEDBUTTON has an EXECUTE option for specifying a command or subroutine to run when the button is pressed. Note: In this Alpha release, speedbars are not yet implemented. A pushbutton is a single button that causes an action when pressed. For instance, an OK pushbutton can save and exit from a window, and a Cancel pushbutton can exit without saving. Typically, pushbuttons confirm an entry or selection made in other controls. Use DEFINE PUSHBUTTON to define pushbuttons. In Windows applications, if a window has a menu, the menu typically offers an item for exiting the window. If a window has no menu, push buttons (such as Cancel or Ok) typically exit the window. A window should not contain both push buttons and menu items for exiting. Step 3 - Assign actions ----------------------- You can assign actions to pull-down menu items, push buttons, and to the window itself. Assigning actions to menus is similar to dBASE IV. To assign actions to push buttons and windows, you need to understand a new concept of window selection. Pulldown Menus Assign actions to pull-down menus with ON SELECTION PULLDOWN. Typically, ON SELECTION PULLDOWN calls a procedure that uses CHOICE() or PROMPT() to determine which item was selected, then branches to other commands based on the selection. Window Selection Selecting a window accepts changes made to the window's controls, much like Ctrl-W accepts values in dBASE DOS. A user selects a window by: - Clicking on a pushbutton - Pressing Enter when the cursor is in the window (See Enter key behavior in Step 4 for details.) - Pressing Ctrl-Enter A user exits a window without selecting it by: - Pressing Esc. You can prevent this with the NoEscape option of OPEN WINDOW, or passing a logical escape parameter to READMODAL(). - Double-clicking in the window's control box, or selecting Close from the control menu, if the window has a control box. - Pressing Ctrl-F4. Use ON SELECTION WINDOW to specify a procedure to execute when a window is selected. Typically, if a window contains one or more push buttons, the ON SELECTION WINDOW procedure uses ACTIVECONTROL() to determine which push button was pressed, then branches to other commands. Push buttons differ from other controls in that one push button is always chosen when the user selects the window. The chosen push button is either the one the user presses, or the default push button if none is pressed. Trapping keystrokes You can assign actions to keystrokes, using the familiar dBASE DOS command, ON KEY. However, certain keystroke combinations are common to all Windows applications. For instance, Alt-F4 closes the active window or dialog box. Your application should not map other behavior to these reserved key combinations. Step 4 - Read the window ------------------------ Bladerunner provides two methods for reading windows: READMODAL() and OPEN WINDOW. READMODAL() Use READMODAL( <window name> ) to stop program execution and read a window. READMODAL() performs a "modal" read of a window. That is, it activates the window with exclusive focus -- the user cannot change focus to another window without first exiting the READMODAL() window. You can use READMODAL() in a command line the same way you would use other fuctions, like GETFILE(), that display a dialog box and return a value. By default, READMODAL() returns the name of the control that has focus when the user selects the window. (See "Window Selection" in Step 3.) You can query the READMODAL() return value to determine the user's action. DEFINE WINDOW Alert FROM 5,5 to 20,65 OF DESKTOP DEFINE PUSHBUTTON Ok OF Alert at 2,2 PROMPT "OK" DEFINE PUSHBUTTON Cancel OF Alert at 2,14 PROMPT "Cancel" ReturnVal = ReadModal("Alert") IF ReturnVal = "OK" DO OKProc ELSE DO CancelProc ENDIF You can specify your own return value for READMODAL() using the WITH option of CLOSE WINDOW. This makes it easy to re-use your window and dialog box definitions. The following example displays the Alert window and returns "My return value." DEFINE WINDOW Alert FROM 5,5 to 20,65 OF DESKTOP DEFINE PUSHBUTTON Ok OF Alert at 2,2 PROMPT "OK" DEFINE PUSHBUTTON Cancel OF Alert at 2,14 PROMPT "Cancel" ON SELECTION WINDOW Alert CLOSE WINDOW WITH "My return value" ReturnVal = ReadModal("Alert") You can nest READMODAL() statements. For instance, a window displayed with READMODAL() can contain a push button that launches another READMODAL() window. In this case, the user must exit the second window, then the first window, before switching focus to another window. OPEN WINDOW OPEN WINDOW performs a "non-modal" read of a window; the user can switch focus to another window without exiting the current window. Choose OPEN WINDOW over READMODAL() when you want to have more than one window active simultaneously. Also, unlike READMODAL(), OPEN WINDOW does not stop program execution. This allows you to execute more OPEN WINDOW commands, or any other code, after reading a window. While OPEN WINDOW represents a break from traditional dBASE coding techniques, where READ commands temporarily halt execution, it allows you to design true event-driven applications. A typical event-driven application simply sets up the environment, and creates and displays its windows. Further execution is determined by the user. Having execution continue after OPEN WINDOW, raises certain issues your program needs to handle. Here are the issues with our current recommendations (better solutions should follow this Alpha release -- your suggestions are encouraged!): - As always occurs in dBASE, non-PUBLIC memory variables are released when the program they are declared in finishes executing. So, if a program creates a window, assigns some memory variables, reads the window with OPEN WINDOW, then ends, the variables are released even though the window is now active. To avoid releasing these variables, you can declare them PUBLIC. - If you define controls that are based on fields in a table (for example, a GET or ENTRYFIELD using a field name), then read the window with OPEN WINDOW, then close the table, the controls will not work because the table is no longer in use. Make sure you don't close the table until the window is closed. - As always occurs in dBASE, functions and procedures declared in a program are unavailable when the program finishes executing. So, if a program contains function declarations, assigns these functions to event handlers such as a VALID or OnClosed option, then reads the window with OPEN WINDOW, the functions are not available when the program ends, even though the window may still be active. To make sure all subroutines attached to event handlers remain available, declare them in a common procedure file that always stays open. The following example shows how you can use OPEN WINDOW to read two windows. The user can launch Calc.prg to activate the Calculator, then launch Invoice.prg to activate the Invoice window. Both windows are then available, and the user can switch focus between them. * Calc.prg - a calculator DEFINE WINDOW Calculator FROM 10,2 * DEFINE controls OF Calulator .... OPEN WINDOW Calculator && Reads Calculator * More code here, if necessary .... RETURN * Invoice.prg - entry window for an invoice DEFINE WINDOW Invoice FROM 1,1 * DEFINE controls OF Invoice .... OPEN WINDOW Invoice && Reads Invoice * More code here, if necessary .... RETURN Enter key behavior One of the differences between dBASE DOS and Windows applications is the behavior of the Enter key. In dBASE DOS, pressing the Enter key moves the cursor to the next GET; pressing Enter on the last GET terminates the READ. In Windows applications, the Tab key typically moves to the next control. Pressing Enter accepts the controls much like Ctrl-W does in dBASE DOS. In Bladerunner, pressing Enter when the cursor is in the window body, but not in an editor object, accepts and exits the window. Tab and Shift-Tab move the cursor to the next and previous controls respectively. While the Windows Enter key behavior is preferable in a Windows application, you might want to retain the DOS behavior to maintain consistency with your DOS applications. Bladerunner provides SET CUAENTER to specify the behavior of the Enter key. SET CUAENTER OFF causes the Enter key to behave as in dBASE DOS; SET CUAENTER ON follows the Windows behavior. Ctrl-Enter accepts and exits and window regardless of the SET CUAENTER setting. Upgrading dBASE DOS screen forms -------------------------------- The Bladerunner UI language extensions replace the familiar dBASE DOS @...SAY/GET commands with the new DEFINE commands, DEFINE TEXT and DEFINE ENTRYFIELD. But that doesn't mean you have to stop using @...SAY/GET. To help you upgrade your dBASE DOS screen forms, Bladerunner provides two new commands, SET WINDOW TO <window name> and SET WINDOW ON. These commands direct @...SAY/GET output to <window name>. You can then define new controls for <window name> without re-writing your @...SAY/GETs. Follow these steps: 1.If your screen form is displayed in a window, consider adding some of the Bladerunner options to your DEFINE WINDOW command, such as DLGFRAME or AUTOSIZE. Otherwise, define a new window. 2.Replace the ACTIVATE WINDOW command with SET WINDOW TO <window name> and SET WINDOW ON. 3.Define any new controls you want to add to your form. 4.If you activate your form with SET FORMAT TO, remove that line. Instead, run the format file like a program, as DO <format file name>. 5.Replace the READ command with READMODAL(). Here is a sample dBASE DOS screen form (Assume an open table contains the fields, FName, LName, and Color): DEFINE WINDOW SelColor FROM 1,1 to 12,50 ACTIVATE WINDOW SelColor @ 2,10 SAY "First Name" GET FName @ 4,10 SAY "Last Name" GET LName @ 6,10 SAY "Color choice" GET Color READ Here is the same screen form upgraded to Bladerunner: DEFINE WINDOW SelColor FROM 1,1 AUTOSIZE SET WINDOW TO SelColor SET WINDOW ON @ 2,10 SAY "First Name" GET FName @ 4,10 SAY "Last Name GET LName DEFINE RADIOBUTTON RadioClr WITH Color OF SelColor AT 6,23; PROMPT "Red" PICK "R", "Green" PICK "G", "Blue" PICK "B"; HORIZONTAL READMODAL("SelColor") ------------------------> EOF: UI_exten.TXT <--------------------